home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_automake.idb / usr / freeware / info / automake.info-1.z / automake.info-1
Encoding:
GNU Info File  |  1999-07-16  |  48.8 KB  |  1,269 lines
  1. This is automake.info, produced by Makeinfo version 3.12b from
  2. automake.texi.
  3.  
  4. INFO-DIR-SECTION GNU admin
  5. START-INFO-DIR-ENTRY
  6. * automake: (automake).        Making Makefile.in's
  7. END-INFO-DIR-ENTRY
  8.  
  9. INFO-DIR-SECTION Individual utilities
  10. START-INFO-DIR-ENTRY
  11. * aclocal: (automake)Invoking aclocal.          Generating aclocal.m4
  12. END-INFO-DIR-ENTRY
  13.  
  14.    This file documents GNU automake 1.4
  15.  
  16.    Copyright (C) 1995, 96, 97, 98 Free Software Foundation, Inc.
  17.  
  18.    Permission is granted to make and distribute verbatim copies of this
  19. manual provided the copyright notice and this permission notice are
  20. preserved on all copies.
  21.  
  22.    Permission is granted to copy and distribute modified versions of
  23. this manual under the conditions for verbatim copying, provided that
  24. the entire resulting derived work is distributed under the terms of a
  25. permission notice identical to this one.
  26.  
  27.    Permission is granted to copy and distribute translations of this
  28. manual into another language, under the above conditions for modified
  29. versions, except that this permission notice may be stated in a
  30. translation approved by the Foundation.
  31.  
  32. 
  33. File: automake.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  34.  
  35. GNU Automake
  36. ************
  37.  
  38.    This file documents the GNU Automake package for creating GNU
  39. Standards-compliant Makefiles from template files.  This edition
  40. documents version 1.4.
  41.  
  42. * Menu:
  43.  
  44. * Introduction::                Automake's purpose
  45. * Generalities::                General ideas
  46. * Examples::                    Some example packages
  47. * Invoking Automake::           Creating a Makefile.in
  48. * configure::                   Scanning configure.in
  49. * Top level::                   The top-level Makefile.am
  50. * Programs::                    Building programs and libraries
  51. * Other objects::               Other derived objects
  52. * Other GNU Tools::             Other GNU Tools
  53. * Documentation::               Building documentation
  54. * Install::                     What gets installed
  55. * Clean::                       What gets cleaned
  56. * Dist::                        What goes in a distribution
  57. * Tests::                       Support for test suites
  58. * Options::                     Changing Automake's behavior
  59. * Miscellaneous::               Miscellaneous rules
  60. * Include::                     Including extra files in an Automake template.
  61. * Conditionals::                Conditionals
  62. * Gnits::                       The effect of `--gnu' and `--gnits'
  63. * Cygnus::                      The effect of `--cygnus'
  64. * Extending::                   Extending Automake
  65. * Distributing::                Distributing the Makefile.in
  66. * Future::                      Some ideas for the future
  67. * Macro and Variable Index::
  68. * General Index::
  69.  
  70. 
  71. File: automake.info,  Node: Introduction,  Next: Generalities,  Prev: Top,  Up: Top
  72.  
  73. Introduction
  74. ************
  75.  
  76.    Automake is a tool for automatically generating `Makefile.in's from
  77. files called `Makefile.am'.  Each `Makefile.am' is basically a series
  78. of `make' macro definitions (with rules being thrown in occasionally).
  79. The generated `Makefile.in's are compliant with the GNU Makefile
  80. standards.
  81.  
  82.    The GNU Makefile Standards Document (*note Makefile Conventions:
  83. (standards)Makefile Conventions.)  is long, complicated, and subject to
  84. change.  The goal of Automake is to remove the burden of Makefile
  85. maintenance from the back of the individual GNU maintainer (and put it
  86. on the back of the Automake maintainer).
  87.  
  88.    The typical Automake input file is simply a series of macro
  89. definitions.  Each such file is processed to create a `Makefile.in'.
  90. There should generally be one `Makefile.am' per directory of a project.
  91.  
  92.    Automake does constrain a project in certain ways; for instance it
  93. assumes that the project uses Autoconf (*note Introduction:
  94. (autoconf)Top.), and enforces certain restrictions on the
  95. `configure.in' contents.
  96.  
  97.    Automake requires `perl' in order to generate the `Makefile.in's.
  98. However, the distributions created by Automake are fully GNU
  99. standards-compliant, and do not require `perl' in order to be built.
  100.  
  101.    Mail suggestions and bug reports for Automake to
  102. <bug-automake@gnu.org>.
  103.  
  104. 
  105. File: automake.info,  Node: Generalities,  Next: Examples,  Prev: Introduction,  Up: Top
  106.  
  107. General ideas
  108. *************
  109.  
  110.    The following sections cover a few basic ideas that will help you
  111. understand how Automake works.
  112.  
  113. * Menu:
  114.  
  115. * General Operation::           General operation of Automake
  116. * Depth::                       The kinds of packages
  117. * Strictness::                  Standards conformance checking
  118. * Uniform::                     The Uniform Naming Scheme
  119. * Canonicalization::            How derived variables are named
  120.  
  121. 
  122. File: automake.info,  Node: General Operation,  Next: Depth,  Prev: Generalities,  Up: Generalities
  123.  
  124. General Operation
  125. =================
  126.  
  127.    Automake works by reading a `Makefile.am' and generating a
  128. `Makefile.in'.  Certain macros and targets defined in the `Makefile.am'
  129. instruct Automake to generate more specialized code; for instance, a
  130. `bin_PROGRAMS' macro definition will cause targets for compiling and
  131. linking programs to be generated.
  132.  
  133.    The macro definitions and targets in the `Makefile.am' are copied
  134. verbatim into the generated file.  This allows you to add arbitrary code
  135. into the generated `Makefile.in'.  For instance the Automake
  136. distribution includes a non-standard `cvs-dist' target, which the
  137. Automake maintainer uses to make distributions from his source control
  138. system.
  139.  
  140.    Note that GNU make extensions are not recognized by Automake.  Using
  141. such extensions in a `Makefile.am' will lead to errors or confusing
  142. behavior.
  143.  
  144.    Automake tries to group comments with adjoining targets and macro
  145. definitions in an intelligent way.
  146.  
  147.    A target defined in `Makefile.am' generally overrides any such
  148. target of a similar name that would be automatically generated by
  149. `automake'.  Although this is a supported feature, it is generally best
  150. to avoid making use of it, as sometimes the generated rules are very
  151. particular.
  152.  
  153.    Similarly, a macro defined in `Makefile.am' will override any
  154. definition of the macro that `automake' would ordinarily create.  This
  155. feature is more often useful than the ability to override a target
  156. definition.  Be warned that many of the macros generated by `automake'
  157. are considered to be for internal use only, and their names might
  158. change in future releases.
  159.  
  160.    When examining a macro definition, Automake will recursively examine
  161. macros referenced in the definition.  For example, if Automake is
  162. looking at the content of `foo_SOURCES' in this snippet
  163.  
  164.      xs = a.c b.c
  165.      foo_SOURCES = c.c $(xs)
  166.  
  167.    it would use the files `a.c', `b.c', and `c.c' as the contents of
  168. `foo_SOURCES'.
  169.  
  170.    Automake also allows a form of comment which is _not_ copied into
  171. the output; all lines beginning with `##' are completely ignored by
  172. Automake.
  173.  
  174.    It is customary to make the first line of `Makefile.am' read:
  175.  
  176.      ## Process this file with automake to produce Makefile.in
  177.  
  178. 
  179. File: automake.info,  Node: Depth,  Next: Strictness,  Prev: General Operation,  Up: Generalities
  180.  
  181. Depth
  182. =====
  183.  
  184.    `automake' supports three kinds of directory hierarchy: `flat',
  185. `shallow', and `deep'.
  186.  
  187.    A "flat" package is one in which all the files are in a single
  188. directory.  The `Makefile.am' for such a package by definition lacks a
  189. `SUBDIRS' macro.  An example of such a package is `termutils'.
  190.  
  191.    A "deep" package is one in which all the source lies in
  192. subdirectories; the top level directory contains mainly configuration
  193. information.  GNU `cpio' is a good example of such a package, as is GNU
  194. `tar'.  The top level `Makefile.am' for a deep package will contain a
  195. `SUBDIRS' macro, but no other macros to define objects which are built.
  196.  
  197.    A "shallow" package is one in which the primary source resides in
  198. the top-level directory, while various parts (typically libraries)
  199. reside in subdirectories.  Automake is one such package (as is GNU
  200. `make', which does not currently use `automake').
  201.  
  202. 
  203. File: automake.info,  Node: Strictness,  Next: Uniform,  Prev: Depth,  Up: Generalities
  204.  
  205. Strictness
  206. ==========
  207.  
  208.    While Automake is intended to be used by maintainers of GNU
  209. packages, it does make some effort to accommodate those who wish to use
  210. it, but do not want to use all the GNU conventions.
  211.  
  212.    To this end, Automake supports three levels of "strictness"--the
  213. strictness indicating how stringently Automake should check standards
  214. conformance.
  215.  
  216.    The valid strictness levels are:
  217.  
  218. `foreign'
  219.      Automake will check for only those things which are absolutely
  220.      required for proper operations.  For instance, whereas GNU
  221.      standards dictate the existence of a `NEWS' file, it will not be
  222.      required in this mode.  The name comes from the fact that Automake
  223.      is intended to be used for GNU programs; these relaxed rules are
  224.      not the standard mode of operation.
  225.  
  226. `gnu'
  227.      Automake will check--as much as possible--for compliance to the GNU
  228.      standards for packages.  This is the default.
  229.  
  230. `gnits'
  231.      Automake will check for compliance to the as-yet-unwritten "Gnits
  232.      standards".  These are based on the GNU standards, but are even
  233.      more detailed.  Unless you are a Gnits standards contributor, it is
  234.      recommended that you avoid this option until such time as the Gnits
  235.      standard is actually published.
  236.  
  237.    For more information on the precise implications of the strictness
  238. level, see *Note Gnits::.
  239.  
  240. 
  241. File: automake.info,  Node: Uniform,  Next: Canonicalization,  Prev: Strictness,  Up: Generalities
  242.  
  243. The Uniform Naming Scheme
  244. =========================
  245.  
  246.    Automake macros (from here on referred to as _variables_) generally
  247. follow a "uniform naming scheme" that makes it easy to decide how
  248. programs (and other derived objects) are built, and how they are
  249. installed.  This scheme also supports `configure' time determination of
  250. what should be built.
  251.  
  252.    At `make' time, certain variables are used to determine which
  253. objects are to be built.  These variables are called "primary
  254. variables".  For instance, the primary variable `PROGRAMS' holds a list
  255. of programs which are to be compiled and linked.
  256.  
  257.    A different set of variables is used to decide where the built
  258. objects should be installed.  These variables are named after the
  259. primary variables, but have a prefix indicating which standard
  260. directory should be used as the installation directory.  The standard
  261. directory names are given in the GNU standards (*note Directory
  262. Variables: (standards)Directory Variables.).  Automake extends this
  263. list with `pkglibdir', `pkgincludedir', and `pkgdatadir'; these are the
  264. same as the non-`pkg' versions, but with `@PACKAGE@' appended.  For
  265. instance, `pkglibdir' is defined as `$(datadir)/@PACKAGE@'.
  266.  
  267.    For each primary, there is one additional variable named by
  268. prepending `EXTRA_' to the primary name.  This variable is used to list
  269. objects which may or may not be built, depending on what `configure'
  270. decides.  This variable is required because Automake must statically
  271. know the entire list of objects that may be built in order to generate
  272. a `Makefile.in' that will work in all cases.
  273.  
  274.    For instance, `cpio' decides at configure time which programs are
  275. built.  Some of the programs are installed in `bindir', and some are
  276. installed in `sbindir':
  277.  
  278.      EXTRA_PROGRAMS = mt rmt
  279.      bin_PROGRAMS = cpio pax
  280.      sbin_PROGRAMS = @PROGRAMS@
  281.  
  282.    Defining a primary variable without a prefix (e.g. `PROGRAMS') is an
  283. error.
  284.  
  285.    Note that the common `dir' suffix is left off when constructing the
  286. variable names; thus one writes `bin_PROGRAMS' and not
  287. `bindir_PROGRAMS'.
  288.  
  289.    Not every sort of object can be installed in every directory.
  290. Automake will flag those attempts it finds in error.  Automake will
  291. also diagnose obvious misspellings in directory names.
  292.  
  293.    Sometimes the standard directories--even as augmented by Automake--
  294. are not enough.  In particular it is sometimes useful, for clarity, to
  295. install objects in a subdirectory of some predefined directory.  To this
  296. end, Automake allows you to extend the list of possible installation
  297. directories.  A given prefix (e.g. `zar') is valid if a variable of the
  298. same name with `dir' appended is defined (e.g. `zardir').
  299.  
  300.    For instance, until HTML support is part of Automake, you could use
  301. this to install raw HTML documentation:
  302.  
  303.      htmldir = $(prefix)/html
  304.      html_DATA = automake.html
  305.  
  306.    The special prefix `noinst' indicates that the objects in question
  307. should not be installed at all.
  308.  
  309.    The special prefix `check' indicates that the objects in question
  310. should not be built until the `make check' command is run.
  311.  
  312.    Possible primary names are `PROGRAMS', `LIBRARIES', `LISP',
  313. `SCRIPTS', `DATA', `HEADERS', `MANS', and `TEXINFOS'.
  314.  
  315. 
  316. File: automake.info,  Node: Canonicalization,  Prev: Uniform,  Up: Generalities
  317.  
  318. How derived variables are named
  319. ===============================
  320.  
  321.    Sometimes a Makefile variable name is derived from some text the user
  322. supplies.  For instance, program names are rewritten into Makefile macro
  323. names.  Automake canonicalizes this text, so that it does not have to
  324. follow Makefile macro naming rules.  All characters in the name except
  325. for letters, numbers, and the underscore are turned into underscores
  326. when making macro references.  For example, if your program is named
  327. `sniff-glue', the derived variable name would be `sniff_glue_SOURCES',
  328. not `sniff-glue_SOURCES'.
  329.  
  330. 
  331. File: automake.info,  Node: Examples,  Next: Invoking Automake,  Prev: Generalities,  Up: Top
  332.  
  333. Some example packages
  334. *********************
  335.  
  336. * Menu:
  337.  
  338. * Complete::                    A simple example, start to finish
  339. * Hello::                       A classic program
  340. * etags::                       Building etags and ctags
  341.  
  342. 
  343. File: automake.info,  Node: Complete,  Next: Hello,  Prev: Examples,  Up: Examples
  344.  
  345. A simple example, start to finish
  346. =================================
  347.  
  348.    Let's suppose you just finished writing `zardoz', a program to make
  349. your head float from vortex to vortex.  You've been using Autoconf to
  350. provide a portability framework, but your `Makefile.in's have been
  351. ad-hoc.  You want to make them bulletproof, so you turn to Automake.
  352.  
  353.    The first step is to update your `configure.in' to include the
  354. commands that `automake' needs.  The simplest way to do this is to add
  355. an `AM_INIT_AUTOMAKE' call just after `AC_INIT':
  356.  
  357.      AM_INIT_AUTOMAKE(zardoz, 1.0)
  358.  
  359.    Since your program doesn't have any complicating factors (e.g., it
  360. doesn't use `gettext', it doesn't want to build a shared library),
  361. you're done with this part.  That was easy!
  362.  
  363.    Now you must regenerate `configure'.  But to do that, you'll need to
  364. tell `autoconf' how to find the new macro you've used.  The easiest way
  365. to do this is to use the `aclocal' program to generate your
  366. `aclocal.m4' for you.  But wait... you already have an `aclocal.m4',
  367. because you had to write some hairy macros for your program.  The
  368. `aclocal' program lets you put your own macros into `acinclude.m4', so
  369. simply rename and then run:
  370.  
  371.      mv aclocal.m4 acinclude.m4
  372.      aclocal
  373.      autoconf
  374.  
  375.    Now it is time to write your `Makefile.am' for `zardoz'.  Since
  376. `zardoz' is a user program, you want to install it where the rest of
  377. the user programs go.  Additionally, `zardoz' has some Texinfo
  378. documentation.  Your `configure.in' script uses `AC_REPLACE_FUNCS', so
  379. you need to link against `@LIBOBJS@'.  So here's what you'd write:
  380.  
  381.      bin_PROGRAMS = zardoz
  382.      zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
  383.      zardoz_LDADD = @LIBOBJS@
  384.      
  385.      info_TEXINFOS = zardoz.texi
  386.  
  387.    Now you can run `automake --add-missing' to generate your
  388. `Makefile.in' and grab any auxiliary files you might need, and you're
  389. done!
  390.  
  391. 
  392. File: automake.info,  Node: Hello,  Next: etags,  Prev: Complete,  Up: Examples
  393.  
  394. A classic program
  395. =================
  396.  
  397.    GNU hello (ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz) is
  398. renowned for its classic simplicity and versatility.  This section shows
  399. how Automake could be used with the GNU Hello package.  The examples
  400. below are from the latest beta version of GNU Hello, but with all of the
  401. maintainer-only code stripped out, as well as all copyright comments.
  402.  
  403.    Of course, GNU Hello is somewhat more featureful than your
  404. traditional two-liner.  GNU Hello is internationalized, does option
  405. processing, and has a manual and a test suite.  GNU Hello is a deep
  406. package.
  407.  
  408.    Here is the `configure.in' from GNU Hello:
  409.  
  410.      dnl Process this file with autoconf to produce a configure script.
  411.      AC_INIT(src/hello.c)
  412.      AM_INIT_AUTOMAKE(hello, 1.3.11)
  413.      AM_CONFIG_HEADER(config.h)
  414.      
  415.      dnl Set of available languages.
  416.      ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
  417.      
  418.      dnl Checks for programs.
  419.      AC_PROG_CC
  420.      AC_ISC_POSIX
  421.      
  422.      dnl Checks for libraries.
  423.      
  424.      dnl Checks for header files.
  425.      AC_STDC_HEADERS
  426.      AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
  427.      
  428.      dnl Checks for library functions.
  429.      AC_FUNC_ALLOCA
  430.      
  431.      dnl Check for st_blksize in struct stat
  432.      AC_ST_BLKSIZE
  433.      
  434.      dnl internationalization macros
  435.      AM_GNU_GETTEXT
  436.      AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
  437.                 src/Makefile tests/Makefile tests/hello],
  438.         [chmod +x tests/hello])
  439.  
  440.    The `AM_' macros are provided by Automake (or the Gettext library);
  441. the rest are standard Autoconf macros.
  442.  
  443.    The top-level `Makefile.am':
  444.  
  445.      EXTRA_DIST = BUGS ChangeLog.O
  446.      SUBDIRS = doc intl po src tests
  447.  
  448.    As you can see, all the work here is really done in subdirectories.
  449.  
  450.    The `po' and `intl' directories are automatically generated using
  451. `gettextize'; they will not be discussed here.
  452.  
  453.    In `doc/Makefile.am' we see:
  454.  
  455.      info_TEXINFOS = hello.texi
  456.      hello_TEXINFOS = gpl.texi
  457.  
  458.    This is sufficient to build, install, and distribute the GNU Hello
  459. manual.
  460.  
  461.    Here is `tests/Makefile.am':
  462.  
  463.      TESTS = hello
  464.      EXTRA_DIST = hello.in testdata
  465.  
  466.    The script `hello' is generated by `configure', and is the only test
  467. case.  `make check' will run this test.
  468.  
  469.    Last we have `src/Makefile.am', where all the real work is done:
  470.  
  471.      bin_PROGRAMS = hello
  472.      hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
  473.      hello_LDADD = @INTLLIBS@ @ALLOCA@
  474.      localedir = $(datadir)/locale
  475.      INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
  476.  
  477. 
  478. File: automake.info,  Node: etags,  Prev: Hello,  Up: Examples
  479.  
  480. Building etags and ctags
  481. ========================
  482.  
  483.    Here is another, trickier example.  It shows how to generate two
  484. programs (`ctags' and `etags') from the same source file (`etags.c').
  485. The difficult part is that each compilation of `etags.c' requires
  486. different `cpp' flags.
  487.  
  488.      bin_PROGRAMS = etags ctags
  489.      ctags_SOURCES =
  490.      ctags_LDADD = ctags.o
  491.      
  492.      etags.o: etags.c
  493.              $(COMPILE) -DETAGS_REGEXPS -c etags.c
  494.      
  495.      ctags.o: etags.c
  496.              $(COMPILE) -DCTAGS -o ctags.o -c etags.c
  497.  
  498.    Note that `ctags_SOURCES' is defined to be empty--that way no
  499. implicit value is substituted.  The implicit value, however, is used to
  500. generate `etags' from `etags.o'.
  501.  
  502.    `ctags_LDADD' is used to get `ctags.o' into the link line.
  503. `ctags_DEPENDENCIES' is generated by Automake.
  504.  
  505.    The above rules won't work if your compiler doesn't accept both `-c'
  506. and `-o'.  The simplest fix for this is to introduce a bogus dependency
  507. (to avoid problems with a parallel `make'):
  508.  
  509.      etags.o: etags.c ctags.o
  510.              $(COMPILE) -DETAGS_REGEXPS -c etags.c
  511.      
  512.      ctags.o: etags.c
  513.              $(COMPILE) -DCTAGS -c etags.c && mv etags.o ctags.o
  514.  
  515.    Also, these explicit rules do not work if the de-ANSI-fication
  516. feature is used (*note ANSI::.).  Supporting de-ANSI-fication requires
  517. a little more work:
  518.  
  519.      etags._o: etags._c ctags.o
  520.              $(COMPILE) -DETAGS_REGEXPS -c etags.c
  521.      
  522.      ctags._o: etags._c
  523.              $(COMPILE) -DCTAGS -c etags.c && mv etags._o ctags.o
  524.  
  525. 
  526. File: automake.info,  Node: Invoking Automake,  Next: configure,  Prev: Examples,  Up: Top
  527.  
  528. Creating a `Makefile.in'
  529. ************************
  530.  
  531.    To create all the `Makefile.in's for a package, run the `automake'
  532. program in the top level directory, with no arguments.  `automake' will
  533. automatically find each appropriate `Makefile.am' (by scanning
  534. `configure.in'; *note configure::.)  and generate the corresponding
  535. `Makefile.in'.  Note that `automake' has a rather simplistic view of
  536. what constitutes a package; it assumes that a package has only one
  537. `configure.in', at the top.  If your package has multiple
  538. `configure.in's, then you must run `automake' in each directory holding
  539. a `configure.in'.
  540.  
  541.    You can optionally give `automake' an argument; `.am' is appended to
  542. the argument and the result is used as the name of the input file.
  543. This feature is generally only used to automatically rebuild an
  544. out-of-date `Makefile.in'.  Note that `automake' must always be run
  545. from the topmost directory of a project, even if being used to
  546. regenerate the `Makefile.in' in some subdirectory.  This is necessary
  547. because `automake' must scan `configure.in', and because `automake'
  548. uses the knowledge that a `Makefile.in' is in a subdirectory to change
  549. its behavior in some cases.
  550.  
  551.    `automake' accepts the following options:
  552.  
  553. `-a'
  554. `--add-missing'
  555.      Automake requires certain common files to exist in certain
  556.      situations; for instance `config.guess' is required if
  557.      `configure.in' runs `AC_CANONICAL_HOST'.  Automake is distributed
  558.      with several of these files; this option will cause the missing
  559.      ones to be automatically added to the package, whenever possible.
  560.      In general if Automake tells you a file is missing, try using this
  561.      option.  By default Automake tries to make a symbolic link
  562.      pointing to its own copy of the missing file; this can be changed
  563.      with `--copy'.
  564.  
  565. `--amdir=DIR'
  566.      Look for Automake data files in directory DIR instead of in the
  567.      installation directory.  This is typically used for debugging.
  568.  
  569. `--build-dir=DIR'
  570.      Tell Automake where the build directory is.  This option is used
  571.      when including dependencies into a `Makefile.in' generated by `make
  572.      dist'; it should not be used otherwise.
  573.  
  574. `-c'
  575.  
  576. `--copy'
  577.      When used with `--add-missing', causes installed files to be
  578.      copied.  The default is to make a symbolic link.
  579.  
  580. `--cygnus'
  581.      Causes the generated `Makefile.in's to follow Cygnus rules, instead
  582.      of GNU or Gnits rules.  For more information, see *Note Cygnus::.
  583.  
  584. `--foreign'
  585.      Set the global strictness to `foreign'.  For more information, see
  586.      *Note Strictness::.
  587.  
  588. `--gnits'
  589.      Set the global strictness to `gnits'.  For more information, see
  590.      *Note Gnits::.
  591.  
  592. `--gnu'
  593.      Set the global strictness to `gnu'.  For more information, see
  594.      *Note Gnits::.  This is the default strictness.
  595.  
  596. `--help'
  597.      Print a summary of the command line options and exit.
  598.  
  599. `-i'
  600. `--include-deps'
  601.      Include all automatically generated dependency information (*note
  602.      Dependencies::.) in the generated `Makefile.in'.  This is
  603.      generally done when making a distribution; see *Note Dist::.
  604.  
  605. `--generate-deps'
  606.      Generate a file concatenating all automatically generated
  607.      dependency information (*note Dependencies::.) into one file,
  608.      `.dep_segment'.  This is generally done when making a
  609.      distribution; see *Note Dist::.  It is useful when maintaining a
  610.      `SMakefile' or makefiles for other platforms (`Makefile.DOS',
  611.      etc.)  It can only be used in conjunction with `--include-deps',
  612.      `--srcdir-name', and `--build-dir'.  Note that if this option is
  613.      given, no other processing is done.
  614.  
  615. `--no-force'
  616.      Ordinarily `automake' creates all `Makefile.in's mentioned in
  617.      `configure.in'.  This option causes it to only update those
  618.      `Makefile.in's which are out of date with respect to one of their
  619.      dependents.
  620.  
  621. `-o DIR'
  622. `--output-dir=DIR'
  623.      Put the generated `Makefile.in' in the directory DIR.  Ordinarily
  624.      each `Makefile.in' is created in the directory of the
  625.      corresponding `Makefile.am'.  This option is used when making
  626.      distributions.
  627.  
  628. `--srcdir-name=DIR'
  629.      Tell Automake the name of the source directory associated with the
  630.      current build.  This option is used when including dependencies
  631.      into a `Makefile.in' generated by `make dist'; it should not be
  632.      used otherwise.
  633.  
  634. `-v'
  635. `--verbose'
  636.      Cause Automake to print information about which files are being
  637.      read or created.
  638.  
  639. `--version'
  640.      Print the version number of Automake and exit.
  641.  
  642. 
  643. File: automake.info,  Node: configure,  Next: Top level,  Prev: Invoking Automake,  Up: Top
  644.  
  645. Scanning `configure.in'
  646. ***********************
  647.  
  648.    Automake scans the package's `configure.in' to determine certain
  649. information about the package.  Some `autoconf' macros are required and
  650. some variables must be defined in `configure.in'.  Automake will also
  651. use information from `configure.in' to further tailor its output.
  652.  
  653.    Automake also supplies some Autoconf macros to make the maintenance
  654. easier.  These macros can automatically be put into your `aclocal.m4'
  655. using the `aclocal' program.
  656.  
  657. * Menu:
  658.  
  659. * Requirements::                Configuration requirements
  660. * Optional::                    Other things Automake recognizes
  661. * Invoking aclocal::            Auto-generating aclocal.m4
  662. * Macros::                      Autoconf macros supplied with Automake
  663. * Extending aclocal::           Writing your own aclocal macros
  664.  
  665. 
  666. File: automake.info,  Node: Requirements,  Next: Optional,  Prev: configure,  Up: configure
  667.  
  668. Configuration requirements
  669. ==========================
  670.  
  671.    The simplest way to meet the basic Automake requirements is to use
  672. the macro `AM_INIT_AUTOMAKE' (*note Macros::.).  But if you prefer, you
  673. can do the required steps by hand:
  674.  
  675.    * Define the variables `PACKAGE' and `VERSION' with `AC_SUBST'.
  676.      `PACKAGE' should be the name of the package as it appears when
  677.      bundled for distribution.  For instance, Automake defines `PACKAGE'
  678.      to be `automake'.  `VERSION' should be the version number of the
  679.      release that is being developed.  We recommend that you make
  680.      `configure.in' the only place in your package where the version
  681.      number is defined; this makes releases simpler.
  682.  
  683.      Automake doesn't do any interpretation of `PACKAGE' or `VERSION',
  684.      except in `Gnits' mode (*note Gnits::.).
  685.  
  686.    * Use the macro `AC_ARG_PROGRAM' if a program or script is installed.
  687.      *Note Transforming Program Names When Installing:
  688.      (autoconf)Transforming Names.
  689.  
  690.    * Use `AC_PROG_MAKE_SET' if the package is not flat.  *Note Creating
  691.      Output Files: (autoconf)Output.
  692.  
  693.    * Use `AM_SANITY_CHECK' to make sure the build environment is sane.
  694.  
  695.    * Call `AC_PROG_INSTALL' (*note Particular Program Checks:
  696.      (autoconf)Particular Programs.).
  697.  
  698.    * Use `AM_MISSING_PROG' to see whether the programs `aclocal',
  699.      `autoconf', `automake', `autoheader', and `makeinfo' are in the
  700.      build environment.  Here is how this is done:
  701.           missing_dir=`cd $ac_aux_dir && pwd`
  702.           AM_MISSING_PROG(ACLOCAL, aclocal, $missing_dir)
  703.           AM_MISSING_PROG(AUTOCONF, autoconf, $missing_dir)
  704.           AM_MISSING_PROG(AUTOMAKE, automake, $missing_dir)
  705.           AM_MISSING_PROG(AUTOHEADER, autoheader, $missing_dir)
  706.           AM_MISSING_PROG(MAKEINFO, makeinfo, $missing_dir)
  707.  
  708.    Here are the other macros which Automake requires but which are not
  709. run by `AM_INIT_AUTOMAKE':
  710.  
  711. `AC_OUTPUT'
  712.      Automake uses this to determine which files to create (*note
  713.      Creating Output Files: (autoconf)Output.).  Listed files named
  714.      `Makefile' are treated as `Makefile's.  Other listed files are
  715.      treated differently.  Currently the only difference is that a
  716.      `Makefile' is removed by `make distclean', while other files are
  717.      removed by `make clean'.
  718.  
  719. 
  720. File: automake.info,  Node: Optional,  Next: Invoking aclocal,  Prev: Requirements,  Up: configure
  721.  
  722. Other things Automake recognizes
  723. ================================
  724.  
  725.    Automake will also recognize the use of certain macros and tailor the
  726. generated `Makefile.in' appropriately.  Currently recognized macros and
  727. their effects are:
  728.  
  729. `AC_CONFIG_HEADER'
  730.      Automake requires the use of `AM_CONFIG_HEADER', which is similar
  731.      to `AC_CONFIG_HEADER' (*note Configuration Header Files:
  732.      (autoconf)Configuration Headers.), but does some useful
  733.      Automake-specific work.
  734.  
  735. `AC_CONFIG_AUX_DIR'
  736.      Automake will look for various helper scripts, such as
  737.      `mkinstalldirs', in the directory named in this macro invocation.
  738.      If not seen, the scripts are looked for in their `standard'
  739.      locations (either the top source directory, or in the source
  740.      directory corresponding to the current `Makefile.am', whichever is
  741.      appropriate).  *Note Finding `configure' Input: (autoconf)Input.
  742.      FIXME: give complete list of things looked for in this directory
  743.  
  744. `AC_PATH_XTRA'
  745.      Automake will insert definitions for the variables defined by
  746.      `AC_PATH_XTRA' into each `Makefile.in' that builds a C program or
  747.      library.  *Note System Services: (autoconf)System Services.
  748.  
  749. `AC_CANONICAL_HOST'
  750. `AC_CHECK_TOOL'
  751.      Automake will ensure that `config.guess' and `config.sub' exist.
  752.      Also, the `Makefile' variables `host_alias' and `host_triplet' are
  753.      introduced.  See both *Note Getting the Canonical System Type:
  754.      (autoconf)Canonicalizing, and *Note Generic Program Checks:
  755.      (autoconf)Generic Programs.
  756.  
  757. `AC_CANONICAL_SYSTEM'
  758.      This is similar to `AC_CANONICAL_HOST', but also defines the
  759.      `Makefile' variables `build_alias' and `target_alias'.  *Note
  760.      Getting the Canonical System Type: (autoconf)Canonicalizing.
  761.  
  762. `AC_FUNC_ALLOCA'
  763. `AC_FUNC_GETLOADAVG'
  764. `AC_FUNC_MEMCMP'
  765. `AC_STRUCT_ST_BLOCKS'
  766. `AC_FUNC_FNMATCH'
  767. `AM_FUNC_STRTOD'
  768. `AC_REPLACE_FUNCS'
  769. `AC_REPLACE_GNU_GETOPT'
  770. `AM_WITH_REGEX'
  771.      Automake will ensure that the appropriate dependencies are
  772.      generated for the objects corresponding to these macros.  Also,
  773.      Automake will verify that the appropriate source files are part of
  774.      the distribution.  Note that Automake does not come with any of
  775.      the C sources required to use these macros, so `automake -a' will
  776.      not install the sources.  *Note A Library::, for more information.
  777.      Also, see *Note Particular Function Checks: (autoconf)Particular
  778.      Functions.
  779.  
  780. `LIBOBJS'
  781.      Automake will detect statements which put `.o' files into
  782.      `LIBOBJS', and will treat these additional files as if they were
  783.      discovered via `AC_REPLACE_FUNCS'.  *Note Generic Function Checks:
  784.      (autoconf)Generic Functions.
  785.  
  786. `AC_PROG_RANLIB'
  787.      This is required if any libraries are built in the package.  *Note
  788.      Particular Program Checks: (autoconf)Particular Programs.
  789.  
  790. `AC_PROG_CXX'
  791.      This is required if any C++ source is included.  *Note Particular
  792.      Program Checks: (autoconf)Particular Programs.
  793.  
  794. `AC_PROG_F77'
  795.      This is required if any Fortran 77 source is included.  This macro
  796.      is distributed with Autoconf version 2.13 and later.  *Note
  797.      Particular Program Checks: (autoconf)Particular Programs.
  798.  
  799. `AC_F77_LIBRARY_LDFLAGS'
  800.      This is required for programs and shared libraries that are a
  801.      mixture of languages that include Fortran 77 (*note Mixing Fortran
  802.      77 With C and C++::.).  *Note Autoconf macros supplied with
  803.      Automake: Macros.
  804.  
  805. `AM_PROG_LIBTOOL'
  806.      Automake will turn on processing for `libtool' (*note
  807.      Introduction: (libtool)Top.).
  808.  
  809. `AC_PROG_YACC'
  810.      If a Yacc source file is seen, then you must either use this macro
  811.      or define the variable `YACC' in `configure.in'.  The former is
  812.      preferred (*note Particular Program Checks: (autoconf)Particular
  813.      Programs.).
  814.  
  815. `AC_DECL_YYTEXT'
  816.      This macro is required if there is Lex source in the package.
  817.      *Note Particular Program Checks: (autoconf)Particular Programs.
  818.  
  819. `AC_PROG_LEX'
  820.      If a Lex source file is seen, then this macro must be used.  *Note
  821.      Particular Program Checks: (autoconf)Particular Programs.
  822.  
  823. `ALL_LINGUAS'
  824.      If Automake sees that this variable is set in `configure.in', it
  825.      will check the `po' directory to ensure that all the named `.po'
  826.      files exist, and that all the `.po' files that exist are named.
  827.  
  828. `AM_C_PROTOTYPES'
  829.      This is required when using automatic de-ANSI-fication; see *Note
  830.      ANSI::.
  831.  
  832. `AM_GNU_GETTEXT'
  833.      This macro is required for packages which use GNU gettext (*note
  834.      gettext::.).  It is distributed with gettext.  If Automake sees
  835.      this macro it ensures that the package meets some of gettext's
  836.      requirements.
  837.  
  838. `AM_MAINTAINER_MODE'
  839.      This macro adds a `--enable-maintainer-mode' option to
  840.      `configure'.  If this is used, `automake' will cause
  841.      `maintainer-only' rules to be turned off by default in the
  842.      generated `Makefile.in's.  This macro is disallowed in `Gnits'
  843.      mode (*note Gnits::.).  This macro defines the `MAINTAINER_MODE'
  844.      conditional, which you can use in your own `Makefile.am'.
  845.  
  846. `AC_SUBST'
  847. `AC_CHECK_TOOL'
  848. `AC_CHECK_PROG'
  849. `AC_CHECK_PROGS'
  850. `AC_PATH_PROG'
  851. `AC_PATH_PROGS'
  852.      For each of these macros, the first argument is automatically
  853.      defined as a variable in each generated `Makefile.in'.  *Note
  854.      Setting Output Variables: (autoconf)Setting Output Variables, and
  855.      *Note Generic Program Checks: (autoconf)Generic Programs.
  856.  
  857. 
  858. File: automake.info,  Node: Invoking aclocal,  Next: Macros,  Prev: Optional,  Up: configure
  859.  
  860. Auto-generating aclocal.m4
  861. ==========================
  862.  
  863.    Automake includes a number of Autoconf macros which can be used in
  864. your package; some of them are actually required by Automake in certain
  865. situations.  These macros must be defined in your `aclocal.m4';
  866. otherwise they will not be seen by `autoconf'.
  867.  
  868.    The `aclocal' program will automatically generate `aclocal.m4' files
  869. based on the contents of `configure.in'.  This provides a convenient
  870. way to get Automake-provided macros, without having to search around.
  871. Also, the `aclocal' mechanism is extensible for use by other packages.
  872.  
  873.    At startup, `aclocal' scans all the `.m4' files it can find, looking
  874. for macro definitions.  Then it scans `configure.in'.  Any mention of
  875. one of the macros found in the first step causes that macro, and any
  876. macros it in turn requires, to be put into `aclocal.m4'.
  877.  
  878.    The contents of `acinclude.m4', if it exists, are also automatically
  879. included in `aclocal.m4'.  This is useful for incorporating local
  880. macros into `configure'.
  881.  
  882.    `aclocal' accepts the following options:
  883.  
  884. `--acdir=DIR'
  885.      Look for the macro files in DIR instead of the installation
  886.      directory.  This is typically used for debugging.
  887.  
  888. `--help'
  889.      Print a summary of the command line options and exit.
  890.  
  891. `-I DIR'
  892.      Add the directory DIR to the list of directories searched for
  893.      `.m4' files.
  894.  
  895. `--output=FILE'
  896.      Cause the output to be put into FILE instead of `aclocal.m4'.
  897.  
  898. `--print-ac-dir'
  899.      Prints the name of the directory which `aclocal' will search to
  900.      find the `.m4' files.  When this option is given, normal processing
  901.      is suppressed.  This option can be used by a package to determine
  902.      where to install a macro file.
  903.  
  904. `--verbose'
  905.      Print the names of the files it examines.
  906.  
  907. `--version'
  908.      Print the version number of Automake and exit.
  909.  
  910. 
  911. File: automake.info,  Node: Macros,  Next: Extending aclocal,  Prev: Invoking aclocal,  Up: configure
  912.  
  913. Autoconf macros supplied with Automake
  914. ======================================
  915.  
  916. `AM_CONFIG_HEADER'
  917.      Automake will generate rules to automatically regenerate the config
  918.      header.  If you do use this macro, you must create the file
  919.      `stamp-h.in' in your source directory.  It can be empty.
  920.  
  921. `AM_ENABLE_MULTILIB'
  922.      This is used when a "multilib" library is being built.  A
  923.      "multilib" library is one that is built multiple times, once per
  924.      target flag combination.  This is only useful when the library is
  925.      intended to be cross-compiled.  The first optional argument is the
  926.      name of the `Makefile' being generated; it defaults to `Makefile'.
  927.      The second option argument is used to find the top source
  928.      directory; it defaults to the empty string (generally this should
  929.      not be used unless you are familiar with the internals).
  930.  
  931. `AM_FUNC_STRTOD'
  932.      If the `strtod' function is not available, or does not work
  933.      correctly (like the one on SunOS 5.4), add `strtod.o' to output
  934.      variable `LIBOBJS'.
  935.  
  936. `AM_FUNC_ERROR_AT_LINE'
  937.      If the function `error_at_line' is not found, then add `error.o'
  938.      to `LIBOBJS'.
  939.  
  940. `AM_FUNC_MKTIME'
  941.      Check for a working `mktime' function.  If not found, add
  942.      `mktime.o' to `LIBOBJS'.
  943.  
  944. `AM_FUNC_OBSTACK'
  945.      Check for the GNU obstacks code; if not found, add `obstack.o' to
  946.      `LIBOBJS'.
  947.  
  948. `AM_C_PROTOTYPES'
  949.      Check to see if function prototypes are understood by the
  950.      compiler.  If so, define `PROTOTYPES' and set the output variables
  951.      `U' and `ANSI2KNR' to the empty string.  Otherwise, set `U' to `_'
  952.      and `ANSI2KNR' to `./ansi2knr'.  Automake uses these values to
  953.      implement automatic de-ANSI-fication.
  954.  
  955. `AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL'
  956.      If the use of `TIOCGWINSZ' requires `<sys/ioctl.h>', then define
  957.      `GWINSZ_IN_SYS_IOCTL'.  Otherwise `TIOCGWINSZ' can be found in
  958.      `<termios.h>'.
  959.  
  960. `AM_INIT_AUTOMAKE'
  961.      Runs many macros that most `configure.in''s need.  This macro has
  962.      two required arguments, the package and the version number.  By
  963.      default this macro `AC_DEFINE''s `PACKAGE' and `VERSION'.  This
  964.      can be avoided by passing in a non-empty third argument.
  965.  
  966. `AM_PATH_LISPDIR'
  967.      Searches for the program `emacs', and, if found, sets the output
  968.      variable `lispdir' to the full path to Emacs' site-lisp directory.
  969.  
  970. `AM_PROG_CC_STDC'
  971.      If the C compiler in not in ANSI C mode by default, try to add an
  972.      option to output variable `CC' to make it so.  This macro tries
  973.      various options that select ANSI C on some system or another.  It
  974.      considers the compiler to be in ANSI C mode if it handles function
  975.      prototypes correctly.
  976.  
  977.      If you use this macro, you should check after calling it whether
  978.      the C compiler has been set to accept ANSI C; if not, the shell
  979.      variable `am_cv_prog_cc_stdc' is set to `no'.  If you wrote your
  980.      source code in ANSI C, you can make an un-ANSIfied copy of it by
  981.      using the `ansi2knr' option (*note ANSI::.).
  982.  
  983. `AM_PROG_LEX'
  984.      Like `AC_PROG_LEX' with `AC_DECL_YYTEXT' (*note Particular Program
  985.      Checks: (autoconf)Particular Programs.), but uses the `missing'
  986.      script on systems that do not have `lex'.  `HP-UX 10' is one such
  987.      system.
  988.  
  989. `AM_SANITY_CHECK'
  990.      This checks to make sure that a file created in the build
  991.      directory is newer than a file in the source directory.  This can
  992.      fail on systems where the clock is set incorrectly.  This macro is
  993.      automatically run from `AM_INIT_AUTOMAKE'.
  994.  
  995. `AM_SYS_POSIX_TERMIOS'
  996.      Check to see if POSIX termios headers and functions are available
  997.      on the system.  If so, set the shell variable
  998.      `am_cv_sys_posix_termios' to `yes'.  If not, set the variable to
  999.      `no'.
  1000.  
  1001. `AM_TYPE_PTRDIFF_T'
  1002.      Define `HAVE_PTRDIFF_T' if the type `ptrdiff_t' is defined in
  1003.      `<stddef.h>'.
  1004.  
  1005. `AM_WITH_DMALLOC'
  1006.      Add support for the dmalloc
  1007.      (ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz) package.  If
  1008.      the user configures with `--with-dmalloc', then define
  1009.      `WITH_DMALLOC' and add `-ldmalloc' to `LIBS'.
  1010.  
  1011. `AM_WITH_REGEX'
  1012.      Adds `--with-regex' to the `configure' command line.  If specified
  1013.      (the default), then the `regex' regular expression library is
  1014.      used, `regex.o' is put into `LIBOBJS', and `WITH_REGEX' is
  1015.      defined..  If `--without-regex' is given, then the `rx' regular
  1016.      expression library is used, and `rx.o' is put into `LIBOBJS'.
  1017.  
  1018. 
  1019. File: automake.info,  Node: Extending aclocal,  Prev: Macros,  Up: configure
  1020.  
  1021. Writing your own aclocal macros
  1022. ===============================
  1023.  
  1024.    The `aclocal' program doesn't have any built-in knowledge of any
  1025. macros, so it is easy to extend it with your own macros.
  1026.  
  1027.    This is mostly used for libraries which want to supply their own
  1028. Autoconf macros for use by other programs.  For instance the `gettext'
  1029. library supplies a macro `AM_GNU_GETTEXT' which should be used by any
  1030. package using `gettext'.  When the library is installed, it installs
  1031. this macro so that `aclocal' will find it.
  1032.  
  1033.    A file of macros should be a series of `AC_DEFUN''s.  The `aclocal'
  1034. programs also understands `AC_REQUIRE', so it is safe to put each macro
  1035. in a separate file.  *Note Prerequisite Macros: (autoconf)Prerequisite
  1036. Macros, and *Note Macro Definitions: (autoconf)Macro Definitions.
  1037.  
  1038.    A macro file's name should end in `.m4'.  Such files should be
  1039. installed in `$(datadir)/aclocal'.
  1040.  
  1041. 
  1042. File: automake.info,  Node: Top level,  Next: Programs,  Prev: configure,  Up: Top
  1043.  
  1044. The top-level `Makefile.am'
  1045. ***************************
  1046.  
  1047.    In non-flat packages, the top level `Makefile.am' must tell Automake
  1048. which subdirectories are to be built.  This is done via the `SUBDIRS'
  1049. variable.
  1050.  
  1051.    The `SUBDIRS' macro holds a list of subdirectories in which building
  1052. of various sorts can occur.  Many targets (e.g. `all') in the generated
  1053. `Makefile' will run both locally and in all specified subdirectories.
  1054. Note that the directories listed in `SUBDIRS' are not required to
  1055. contain `Makefile.am's; only `Makefile's (after configuration).  This
  1056. allows inclusion of libraries from packages which do not use Automake
  1057. (such as `gettext').  The directories mentioned in `SUBDIRS' must be
  1058. direct children of the current directory.  For instance, you cannot put
  1059. `src/subdir' into `SUBDIRS'.
  1060.  
  1061.    In a deep package, the top-level `Makefile.am' is often very short.
  1062. For instance, here is the `Makefile.am' from the GNU Hello distribution:
  1063.  
  1064.      EXTRA_DIST = BUGS ChangeLog.O README-alpha
  1065.      SUBDIRS = doc intl po src tests
  1066.  
  1067.    It is possible to override the `SUBDIRS' variable if, like in the
  1068. case of GNU `Inetutils', you want to only build a subset of the entire
  1069. package.  In your `Makefile.am' include:
  1070.  
  1071.      SUBDIRS = @SUBDIRS@
  1072.  
  1073.    Then in your `configure.in' you can specify:
  1074.  
  1075.      SUBDIRS = "src doc lib po"
  1076.      AC_SUBST(SUBDIRS)
  1077.  
  1078.    The upshot of this is that Automake is tricked into building the
  1079. package to take the subdirs, but doesn't actually bind that list until
  1080. `configure' is run.
  1081.  
  1082.    Although the `SUBDIRS' macro can contain configure substitutions
  1083. (e.g. `@DIRS@'); Automake itself does not actually examine the contents
  1084. of this variable.
  1085.  
  1086.    If `SUBDIRS' is defined, then your `configure.in' must include
  1087. `AC_PROG_MAKE_SET'.
  1088.  
  1089.    The use of `SUBDIRS' is not restricted to just the top-level
  1090. `Makefile.am'.  Automake can be used to construct packages of arbitrary
  1091. depth.
  1092.  
  1093.    By default, Automake generates `Makefiles' which work depth-first
  1094. (`postfix').  However, it is possible to change this ordering.  You can
  1095. do this by putting `.' into `SUBDIRS'.  For instance, putting `.'
  1096. first will cause a `prefix' ordering of directories.
  1097.  
  1098. 
  1099. File: automake.info,  Node: Programs,  Next: Other objects,  Prev: Top level,  Up: Top
  1100.  
  1101. Building Programs and Libraries
  1102. *******************************
  1103.  
  1104.    A large part of Automake's functionality is dedicated to making it
  1105. easy to build programs and libraries.
  1106.  
  1107. * Menu:
  1108.  
  1109. * A Program::                   Building a program
  1110. * A Library::                   Building a library
  1111. * LIBOBJS::                     Special handling for LIBOBJS and ALLOCA
  1112. * A Shared Library::            Building a Libtool library
  1113. * Program variables::           Variables used when building a program
  1114. * Yacc and Lex::                Yacc and Lex support
  1115. * C++ Support::
  1116. * Fortran 77 Support::
  1117. * Support for Other Languages::
  1118. * ANSI::                        Automatic de-ANSI-fication
  1119. * Dependencies::                Automatic dependency tracking
  1120.  
  1121. 
  1122. File: automake.info,  Node: A Program,  Next: A Library,  Prev: Programs,  Up: Programs
  1123.  
  1124. Building a program
  1125. ==================
  1126.  
  1127.    In a directory containing source that gets built into a program (as
  1128. opposed to a library), the `PROGRAMS' primary is used.  Programs can be
  1129. installed in `bindir', `sbindir', `libexecdir', `pkglibdir', or not at
  1130. all (`noinst').
  1131.  
  1132.    For instance:
  1133.  
  1134.      bin_PROGRAMS = hello
  1135.  
  1136.    In this simple case, the resulting `Makefile.in' will contain code
  1137. to generate a program named `hello'.  The variable `hello_SOURCES' is
  1138. used to specify which source files get built into an executable:
  1139.  
  1140.      hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
  1141.  
  1142.    This causes each mentioned `.c' file to be compiled into the
  1143. corresponding `.o'.  Then all are linked to produce `hello'.
  1144.  
  1145.    If `PROG_SOURCES' is needed, but not specified, then it defaults to
  1146. the single file `prog.c'.
  1147.  
  1148.    Multiple programs can be built in a single directory.  Multiple
  1149. programs can share a single source file, which must be listed in each
  1150. `_SOURCES' definition.
  1151.  
  1152.    Header files listed in a `_SOURCES' definition will be included in
  1153. the distribution but otherwise ignored.  In case it isn't obvious, you
  1154. should not include the header file generated by `configure' in an
  1155. `_SOURCES' variable; this file should not be distributed.  Lex (`.l')
  1156. and Yacc (`.y') files can also be listed; see *Note Yacc and Lex::.
  1157.  
  1158.    Automake must know all the source files that could possibly go into a
  1159. program, even if not all the files are built in every circumstance.
  1160. Any files which are only conditionally built should be listed in the
  1161. appropriate `EXTRA_' variable.  For instance, if `hello-linux.c' were
  1162. conditionally included in `hello', the `Makefile.am' would contain:
  1163.  
  1164.      EXTRA_hello_SOURCES = hello-linux.c
  1165.  
  1166.    Similarly, sometimes it is useful to determine the programs that are
  1167. to be built at configure time.  For instance, GNU `cpio' only builds
  1168. `mt' and `rmt' under special circumstances.
  1169.  
  1170.    In this case, you must notify Automake of all the programs that can
  1171. possibly be built, but at the same time cause the generated
  1172. `Makefile.in' to use the programs specified by `configure'.  This is
  1173. done by having `configure' substitute values into each `_PROGRAMS'
  1174. definition, while listing all optionally built programs in
  1175. `EXTRA_PROGRAMS'.
  1176.  
  1177.    If you need to link against libraries that are not found by
  1178. `configure', you can use `LDADD' to do so.  This variable actually can
  1179. be used to add any options to the linker command line.
  1180.  
  1181.    Sometimes, multiple programs are built in one directory but do not
  1182. share the same link-time requirements.  In this case, you can use the
  1183. `PROG_LDADD' variable (where PROG is the name of the program as it
  1184. appears in some `_PROGRAMS' variable, and usually written in lowercase)
  1185. to override the global `LDADD'.  If this variable exists for a given
  1186. program, then that program is not linked using `LDADD'.
  1187.  
  1188.    For instance, in GNU cpio, `pax', `cpio' and `mt' are linked against
  1189. the library `libcpio.a'.  However, `rmt' is built in the same
  1190. directory, and has no such link requirement.  Also, `mt' and `rmt' are
  1191. only built on certain architectures.  Here is what cpio's
  1192. `src/Makefile.am' looks like (abridged):
  1193.  
  1194.      bin_PROGRAMS = cpio pax @MT@
  1195.      libexec_PROGRAMS = @RMT@
  1196.      EXTRA_PROGRAMS = mt rmt
  1197.      
  1198.      LDADD = ../lib/libcpio.a @INTLLIBS@
  1199.      rmt_LDADD =
  1200.      
  1201.      cpio_SOURCES = ...
  1202.      pax_SOURCES = ...
  1203.      mt_SOURCES = ...
  1204.      rmt_SOURCES = ...
  1205.  
  1206.    `PROG_LDADD' is inappropriate for passing program-specific linker
  1207. flags (except for `-l' and `-L').  So, use the `PROG_LDFLAGS' variable
  1208. for this purpose.
  1209.  
  1210.    It is also occasionally useful to have a program depend on some other
  1211. target which is not actually part of that program.  This can be done
  1212. using the `PROG_DEPENDENCIES' variable.  Each program depends on the
  1213. contents of such a variable, but no further interpretation is done.
  1214.  
  1215.    If `PROG_DEPENDENCIES' is not supplied, it is computed by Automake.
  1216. The automatically-assigned value is the contents of `PROG_LDADD', with
  1217. most configure substitutions, `-l', and `-L' options removed.  The
  1218. configure substitutions that are left in are only `@LIBOBJS@' and
  1219. `@ALLOCA@'; these are left because it is known that they will not cause
  1220. an invalid value for `PROG_DEPENDENCIES' to be generated.
  1221.  
  1222. 
  1223. File: automake.info,  Node: A Library,  Next: LIBOBJS,  Prev: A Program,  Up: Programs
  1224.  
  1225. Building a library
  1226. ==================
  1227.  
  1228.    Building a library is much like building a program.  In this case,
  1229. the name of the primary is `LIBRARIES'.  Libraries can be installed in
  1230. `libdir' or `pkglibdir'.
  1231.  
  1232.    *Note A Shared Library::, for information on how to build shared
  1233. libraries using Libtool and the `LTLIBRARIES' primary.
  1234.  
  1235.    Each `_LIBRARIES' variable is a list of the libraries to be built.
  1236. For instance to create a library named `libcpio.a', but not install it,
  1237. you would write:
  1238.  
  1239.      noinst_LIBRARIES = libcpio.a
  1240.  
  1241.    The sources that go into a library are determined exactly as they are
  1242. for programs, via the `_SOURCES' variables.  Note that the library name
  1243. is canonicalized (*note Canonicalization::.), so the `_SOURCES'
  1244. variable corresponding to `liblob.a' is `liblob_a_SOURCES', not
  1245. `liblob.a_SOURCES'.
  1246.  
  1247.    Extra objects can be added to a library using the `LIBRARY_LIBADD'
  1248. variable.  This should be used for objects determined by `configure'.
  1249. Again from `cpio':
  1250.  
  1251.      libcpio_a_LIBADD = @LIBOBJS@ @ALLOCA@
  1252.  
  1253. 
  1254. File: automake.info,  Node: LIBOBJS,  Next: A Shared Library,  Prev: A Library,  Up: Programs
  1255.  
  1256. Special handling for LIBOBJS and ALLOCA
  1257. =======================================
  1258.  
  1259.    Automake explicitly recognizes the use of `@LIBOBJS@' and
  1260. `@ALLOCA@', and uses this information, plus the list of `LIBOBJS' files
  1261. derived from `configure.in' to automatically include the appropriate
  1262. source files in the distribution (*note Dist::.).  These source files
  1263. are also automatically handled in the dependency-tracking scheme; see
  1264. *Note Dependencies::.
  1265.  
  1266.    `@LIBOBJS@' and `@ALLOCA@' are specially recognized in any `_LDADD'
  1267. or `_LIBADD' variable.
  1268.  
  1269.